home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / net / omniORB-2.5.0-src.tar.gz / omniORB-2.5.0-src.tar / omniORB_2.5.0 / include / omniORB2 / omniORB.h < prev    next >
C/C++ Source or Header  |  1998-03-04  |  27KB  |  465 lines
  1. // -*- Mode: C++; -*-
  2. //                            Package   : omniORB2
  3. // omniORB.h                  Created on: 6/2/96
  4. //                            Author    : Sai Lai Lo (sll)
  5. //
  6. //    Copyright (C) 1996, 1997 Olivetti & Oracle Research Laboratory
  7. //
  8. //    This file is part of the omniORB library
  9. //
  10. //    The omniORB library is free software; you can redistribute it and/or
  11. //    modify it under the terms of the GNU Library General Public
  12. //    License as published by the Free Software Foundation; either
  13. //    version 2 of the License, or (at your option) any later version.
  14. //
  15. //    This library is distributed in the hope that it will be useful,
  16. //    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17. //    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18. //    Library General Public License for more details.
  19. //
  20. //    You should have received a copy of the GNU Library General Public
  21. //    License along with this library; if not, write to the Free
  22. //    Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  23. //    02111-1307, USA
  24. //
  25. //
  26. // Description:
  27. //        This is the public API of omniORB2's extension to CORBA.
  28. //      The API is intended to be used in application code.
  29.  
  30. /*
  31.   $Log: omniORB.h,v $
  32.   Revision 1.11  1998/03/04 14:48:47  sll
  33.   Added omniORB::giopServerThreadWrapper.
  34.  
  35.  * Revision 1.10  1998/03/02  17:05:29  ewc
  36.  * Removed scoping from objectKey in class loader (caused problems compiling
  37.  * with MSVC++ 5.0)
  38.  *
  39.  * Revision 1.9  1998/02/25  20:34:59  sll
  40.  * New omniORB::loader class for adding dynamic object loader.
  41.  *
  42.  * Revision 1.8  1998/01/27  16:07:58  ewc
  43.  * Added -ORBtcAliasExpand flag
  44.  *
  45.   Revision 1.7  1997/12/12 18:47:16  sll
  46.   New variable serverName.
  47.  
  48.   Revision 1.6  1997/12/09 20:36:05  sll
  49.   Support for system exception handlers.
  50.   Support for incoming and outgoing rope scavenger threads.
  51.  
  52.  * Revision 1.5  1997/05/06  16:09:39  sll
  53.  * Public release.
  54.  *
  55.  */
  56.  
  57. #ifndef __OMNIORB_H__
  58. #define __OMNIORB_H__
  59.  
  60. class _OMNIORB2_NTDLL_ omniORB {
  61.  
  62. public:
  63.  
  64.   ////////////////////////////////////////////////////////////////////////
  65.   // serverName                                //
  66.   //                                    //
  67.   // omniORB2's idea of the name of the server.  Set to argv[0] by      //
  68.   // ORB_init or changed by command-line option -ORBserverName <name>.  //
  69.   // This name is used in the host-based access control of the IIOP     //
  70.   // gatekeeper.                                                        //
  71.   //                                                                    //
  72.   //                                    //
  73.   static CORBA::String_var serverName;                    //
  74.   ////////////////////////////////////////////////////////////////////////
  75.  
  76.   ///////////////////////////////////////////////////////////////////////
  77.   // Tracing level                                                     //
  78.   //     level 0 - turn off all tracing and informational messages     //
  79.   //     level 1 - informational messages only                         //
  80.   //     level 2 - configuration information                           //
  81.   //     level 5 - the above plus report server thread creation and    //
  82.   //               communication socket shutdown                       //
  83.   //     level 10 - the above plus execution trace messages            //
  84.   //     ...                                                           //
  85.   static CORBA::ULong   traceLevel;                                    //
  86.   //                                                                   //
  87.   //     This value can be changed at runtime either by command-line   //
  88.   //     option: -ORBtraceLevel <n>, or by direct assignment to this   //
  89.   //     variable.                                                     //
  90.   ///////////////////////////////////////////////////////////////////////
  91.  
  92.   ///////////////////////////////////////////////////////////////////////
  93.   // strictIIOP flag                                                   //
  94.   //   Enable vigorous check on incoming IIOP messages                 //
  95.   //                                                                   //
  96.   // In some (sloppy) IIOP implementation, the message size value in   //
  97.   // the header can be larger than the actual body size, i.e. there is //
  98.   // garbage at the end. As the spec does not say the message size     //
  99.   // must match the body size exactly, this is not a clear violation   //
  100.   // of the spec.                                                      //
  101.   //                                                                   //
  102.   // If this flag is non-zero, the incoming message is expected to     //
  103.   // be well behaved. Any messages that have garbage at the end will   //
  104.   // be rejected.                                                      //
  105.   //                                                                   //
  106.   // The default value of this flag is zero and the ORB would silently //
  107.   // skip the unread part. The problem with this behaviour is that the //
  108.   // header message size may actually be garbage value, caused by a bug//
  109.   // in the sender's code. Th receiving thread may forever block on    //
  110.   // the strand as it tries to read more data from it. In this case the//
  111.   // sender won't send anymore as it thinks it has marshalled in all   //
  112.   // the data.                                   //
  113.   static CORBA::Boolean   strictIIOP;                                  //
  114.   //                                                                   //
  115.   //     This value can be changed at runtime either by command-line   //
  116.   //     option: -ORBstrictIIOP <0|1>, or by direct assignment to this //
  117.   //     variable.                                                     //
  118.   ///////////////////////////////////////////////////////////////////////
  119.  
  120.   ///////////////////////////////////////////////////////////////////////
  121.   //  tcAliasExpand flag is used to indicate whether TypeCodes        //
  122.   //              associated with anys should have aliases removed.This//
  123.   //              functionality is included because some ORBs will not //
  124.   //              recognise an Any containing a TypeCode containing    //
  125.   //              aliases to be the same as the actual type contained  //
  126.   //              in the Any. Note that omniORB will always remove     //
  127.   //              top-level aliases, but will not remove aliases from  //
  128.   //              TypeCodes that are members of other TypeCodes (e.g.  //
  129.   //              TypeCodes for members of structs etc.), unless       //
  130.   //              tcAliasExpand is set to 1. There is a performance    //
  131.   //              penalty when inserting into an Any if tcAliasExpand  //
  132.   //              is set to 1. The default value is 0 (i.e. aliases of //
  133.   //              member TypeCodes are not expanded).                  //
  134.   //              Note that aliases won't be expanded when one of the  //
  135.   //              non - type-safe methods of inserting into an Any is  //
  136.   //              used (i.e. when the replace() member function or     //
  137.   //              non - type-safe Any constructor is used. )           //
  138.   ///////////////////////////////////////////////////////////////////////
  139.   static CORBA::Boolean tcAliasExpand;                                 //
  140.   //     This value can be changed at runtime either by command-line   //
  141.   //     option: -ORBtcAliasExpand <0|1>, or by direct assignment to   //
  142.   //     this variable.                                                //
  143.   ///////////////////////////////////////////////////////////////////////
  144.  
  145.   ////////////////////////////////////////////////////////////////////////
  146.   // objectKey is a data type that uniquely identify each object        //
  147.   //           implementation in the same address space. Its actual     //
  148.   //           implmentation is not public. The data type should only   //
  149.   //           be processed in an application by the following utility  //
  150.   //           functions.                                               //
  151.   //                                                                    //
  152.   //                                                                    //
  153.   typedef omniObjectKey objectKey;                                      //
  154.   //                                                                    //
  155.   //  size of the hash table used by hash().                            //
  156.   static const unsigned int hash_table_size;                            //
  157.   //                                                                    //
  158.   //  hash()                                                            //
  159.   //    return the hash value of this key. The return value             //
  160.   //    is between 0 - (hash_table_size - 1);                           //
  161.   static int hash(objectKey& k);                                        //
  162.   //                                                                    //
  163.   // generateNewKey()                                                   //
  164.   //   generate a new key. The key is guaranteed to be temporally       //
  165.   //   unique. On OSs that provide unique process IDs, e.g. unices,     //
  166.   //   the key is guaranteed to be unique among all keys ever generated //
  167.   //   on the same machine.                                             //
  168.   static void generateNewKey(objectKey &k);                             //
  169.   //                                                                    //
  170.   // Return a fixed key value that always hash to 0.                    //
  171.   static objectKey nullkey();                                           //
  172.   //                                                                    //
  173.   // Return non-zero if the keys are the same                           //
  174.   friend int operator==(const objectKey &k1,const objectKey &k2);       //
  175.   //                                                                    //
  176.   // Return non-zero if the keys are different                          //
  177.   friend int operator!=(const objectKey &k1,const objectKey &k2);       //
  178.   //                                                                    //
  179.   //                                                                    //
  180.   typedef _CORBA_Unbounded_Sequence_Octet seqOctets;                    //
  181.   // Convert a key to a sequence of octets.                             //
  182.   static seqOctets* keyToOctetSequence(const objectKey &k1);            //
  183.   //                                                                    //
  184.   // Convert a sequence of octets back to an object key.                //
  185.   // This function may throw a CORBA::MARSHAL exception if the sequence //
  186.   // is not an object key.                                              //
  187.   static objectKey octetSequenceToKey(const seqOctets& seq);            //
  188.   ////////////////////////////////////////////////////////////////////////
  189.  
  190.   ////////////////////////////////////////////////////////////////////////
  191.   // MaxMessageSize()                                                   //
  192.   //                                                                    //
  193.   // returns the ORB-wide limit on the size of GIOP message (excluding  //
  194.   // the header).                                                       //
  195.   //                                                                    //
  196.   static size_t MaxMessageSize();                                       //
  197.   ////////////////////////////////////////////////////////////////////////
  198.  
  199.   ////////////////////////////////////////////////////////////////////////
  200.   // void MaxMessageSize(size_t newvalue)                               //
  201.   //                                                                    //
  202.   // Set the ORB-wide limit on the size of GIOP message (excluding      //
  203.   // the header).                                                       //
  204.   //                                                                    //
  205.   static void MaxMessageSize(size_t newvalue);                          //
  206.   ////////////////////////////////////////////////////////////////////////
  207.  
  208.   ////////////////////////////////////////////////////////////////////////
  209.   enum idleConnType { idleIncoming, idleOutgoing };                     //
  210.   // Idle connections shutdown. The ORB periodically scans all the      //
  211.   // incoming and outgoing connections to detect if they are idle.      //
  212.   // If no operation has passed through a connection for two            //
  213.   // consecutive scan periods, the ORB would treat this connection as   //
  214.   // idle and shut it down.                                             //
  215.   //                                                                    //
  216.   // void idleConnectionScanPeriod() sets the scan period. The argument //
  217.   // is in number of seconds. If the argument is zero, the scan for idle//
  218.   // connection is disabled.                                            //
  219.   static void idleConnectionScanPeriod(idleConnType direction,          //
  220.                        CORBA::ULong sec);               //
  221.   // Note: This function is *non-thread safe*!!! The behaviour of       //
  222.   //       concurrent calls to this function is undefined.              //
  223.   //                                                                    //
  224.   // CORBA::ULong idleConnectionScanPeriod()                            //
  225.   //   Returns the current scan period                                  //
  226.   static CORBA::ULong idleConnectionScanPeriod(idleConnType direction); //
  227.   ////////////////////////////////////////////////////////////////////////
  228.  
  229.   ////////////////////////////////////////////////////////////////////////
  230.   // When an operation is invoked via an object reference, a            //
  231.   // CORBA::TRANSIENT exception may be raised.                 //
  232.   //                                    //
  233.   // By default, the operation will be retried transparently. The ORB     //
  234.   // will retry indefinitely if the operation continues to raise the    //
  235.   // CORBA::TRANSIENT exception. Successive retries will be delayed    //
  236.   // progressively by multiples of                    //
  237.   // omniORB::defaultTransientRetryDelayIncment.  The value is in number//
  238.   // of seconds. The delay will be limited to a maximum specified by    //
  239.   // omniORB::defaultTransientRetryDelayMaximum.            //
  240.   //                                    //
  241.   // This retry behaviour can be overridden by installing an exception    //
  242.   // handler.  An exception handler is a function with the same     //
  243.   // signature as omniORB::transientExceptionHandler_t. The handler     //
  244.   // will be called when a CORBA::TRANSIENT exception is caught by the     //
  245.   // ORB. The handler is passed with three arguments: a <cookie>, the     //
  246.   // no. of retries <n_retries> and the value of the exception caught     //
  247.   // <ex>. The handler is expected to do whatever is appropriate and     //
  248.   // returns a boolean value. If the return value is TRUE (1), the ORB     //
  249.   // would retry the operation again. If the return value is FALSE (0),    //
  250.   // the CORBA::TRANSIENT exception would be re-throw and is expected to//
  251.   // be caught by the application code.                    //
  252.   //                                    //
  253.   // The overloaded functions omniORB::installTransientExceptionHandler //
  254.   // can be used to install the exception handlers for CORBA::TRANSIENT.//
  255.   // Two overloaded forms are available. The first form install an     //
  256.   // exception handler for all object references except for those which //
  257.   // have an exception handler installed by the second form, which takes//
  258.   // an addition argument <obj> to identify the target object reference.//
  259.   // The argument <cookie> is an opaque pointer which will be passed     //
  260.   // on by the ORB when it calls the exception handler.            //
  261.   //                                    //
  262.   typedef CORBA::Boolean (*transientExceptionHandler_t)(void* cookie,    //
  263.                            CORBA::ULong n_retries,     //
  264.                                               const CORBA::TRANSIENT& ex);
  265.   //                                           //
  266.   static void installTransientExceptionHandler(void* cookie,        //
  267.                            transientExceptionHandler_t fn);
  268.   //                                    //
  269.   static void installTransientExceptionHandler(CORBA::Object_ptr obj,   //
  270.                            void* cookie,            //
  271.                                transientExceptionHandler_t fn);
  272.   //                                    //
  273.   static CORBA::ULong defaultTransientRetryDelayIncrement;        //
  274.   static CORBA::ULong defaultTransientRetryDelayMaximum;        //
  275.   ////////////////////////////////////////////////////////////////////////
  276.  
  277.  
  278.   ////////////////////////////////////////////////////////////////////////
  279.   // When an operation is invoked via an object reference, a        //
  280.   // CORBA::COMM_FAILURE exception may be raised.             //
  281.   //                                    //
  282.   // By default, the ORB will pass this exception on to the application.//
  283.   //                                    //
  284.   // This behaviour can be overridden by installing an exception    //
  285.   // handler. The function signature of the handler should be the same     //
  286.   // as omniORB::commFailureExceptionHandler_t. The handlers can be     //
  287.   // installed using the overloaded functions                //
  288.   // omniORB::installCommFailureExceptionHandler. The use of these    //
  289.   // functions is similar to those for the TRANSIENT exception. See     //
  290.   // above for details.                            //
  291.   //                                    //
  292.   typedef CORBA::Boolean (*commFailureExceptionHandler_t)(void* cookie,    //
  293.                         CORBA::ULong n_retries, //
  294.                         const CORBA::COMM_FAILURE& ex);
  295.   //                                    //
  296.   static void installCommFailureExceptionHandler(void* cookie,        //
  297.                          commFailureExceptionHandler_t fn);
  298.   //                                    //
  299.   static void installCommFailureExceptionHandler(CORBA::Object_ptr obj,    //
  300.                          void* cookie,        //
  301.                          commFailureExceptionHandler_t fn);
  302.   ////////////////////////////////////////////////////////////////////////
  303.  
  304.   ////////////////////////////////////////////////////////////////////////
  305.   // When an operation is invoked via an object reference, a system    //
  306.   // exception may be raised. If the exception is either CORBA::TRANSIENT//
  307.   // and CORBA::COMM_FAILURE, the handling of this exception is described//
  308.   // above.                                //
  309.   //                                    //
  310.   // By default, if the exception is neither CORBA::TRANSIENT and    //
  311.   // CORBA::COMM_FAILURE, the ORB will pass this exception on to the    //
  312.   // application.                             //
  313.   //                                    //
  314.   // This behaviour can be overridden by installing an exception handler//
  315.   // The function signature of the handler should be the same as    //
  316.   // omniORB::systemExceptionHandler_t. The handlers can be installed   //
  317.   // using the overloaded functions                    //
  318.   // omniORB::installSystemExceptionHandler.                            //
  319.   // The use of these functions is similar to those for the TRANSIENT    //
  320.   // exception. See above for details. Notice that the installed        //
  321.   // exception handler will only be called when the system exception is //
  322.   // neither CORBA::TRANSIENT nor CORBA::COMM_FAILURE.            //
  323.   //                                    //
  324.   typedef CORBA::Boolean (*systemExceptionHandler_t)(void* cookie,    //
  325.                        CORBA::ULong n_retries,     //
  326.                        const CORBA::SystemException& ex);
  327.   //                                    //
  328.   static void installSystemExceptionHandler(void* cookie,        //
  329.                         systemExceptionHandler_t fn);
  330.   //                                    //
  331.   static void installSystemExceptionHandler(CORBA::Object_ptr obj,    //
  332.                         void* cookie,        //
  333.                         systemExceptionHandler_t fn);
  334.   ////////////////////////////////////////////////////////////////////////
  335.  
  336.   ////////////////////////////////////////////////////////////////////////
  337.   //                                                                    //
  338.   // An application can register a handler for loading objects          //
  339.   // dynamically. The handler should have the signature:                //
  340.   //                                                                    //
  341.   //          omniORB::loader::mapKeyToObject_t                         //
  342.   //                                                                    //
  343.   // When the ORB cannot locate the target object in this address space,//
  344.   // it calls the handler with the object key of the target.            //
  345.   // The handler is expected to instantiate the object, either in       //
  346.   // this address space or in another address space, and returns the    //
  347.   // object reference to the newly instantiated object. The ORB will    //
  348.   // then reply with a LOCATION_FORWARD message to instruct the client  //
  349.   // to retry using the object reference returned by the handler.       //
  350.   // When the handler returns, the ORB assumes ownership of the         //
  351.   // returned value. It will call CORBA::release() on the returned      //
  352.   // value when it has finished with it.                                //
  353.   //                                                                    //
  354.   // The handler may be called concurrently by multi-threads. Hence it  //
  355.   // must be thread-safe.                                               //
  356.   //                                                                    //
  357.   // If the handler cannot load the target object, it should return     //
  358.   // CORBA::Object::_nil(). The object will be treated as non-existing. //
  359.   //                                                                    //
  360.   // The application registers the handler with the ORB at runtime      //
  361.   // using omniORB::loader::set(). This function is not thread-safe.    //
  362.   // Calling this function again will replace the old handler with      //
  363.   // the new one.                                                       //
  364.   //                                                                    //
  365.   class loader {                                                        //
  366.   public:                                                               //
  367.     typedef CORBA::Object_ptr (*mapKeyToObject_t) (                     //
  368.                                        const objectKey& key);           //
  369.                                                                         //
  370.     static void set(mapKeyToObject_t NewKeyToObject);                   //
  371.   };
  372.   ////////////////////////////////////////////////////////////////////////
  373.  
  374.  
  375.   ////////////////////////////////////////////////////////////////////////
  376.   // class giopServerThreadWrapper                                      //
  377.   //                                                                    //
  378.   // At any time, a single instance of this class (a singleton) is      //
  379.   // registered with the runtime.                                       //
  380.   //                                                                    //
  381.   // What is the function of this class?                                //
  382.   //   The runtime uses a number of threads internally to process       //
  383.   //   requests from other address spaces. Each thread starts by        //
  384.   //   calling the run() method of the singleton. The thread            //
  385.   //   will exit when run() returns. The run() method takes two         //
  386.   //   arguments: a callback function <fn> and its argument <arg>.      //
  387.   //   The run() method *MUST* call fn(arg) to pass the control back    //
  388.   //   the runtime at some point. When fn() returns, the run() method   //
  389.   //   should cleanup and returns asap.                                 //
  390.   //                                                                    //
  391.   //   Application can modify the behaviour of run() by installing      //
  392.   //   another singleton using setGiopServerThreadWrapper(). The        //
  393.   //   singleton should be an instance of a derived class of            //
  394.   //   giopServerThreadWrapper. The derived class should overload the   //
  395.   //   virtual function run() to customise its behaviour.               //
  396.   //                                                                    //
  397.   //   For example, to insert the fault handler code for ObjectStore    //
  398.   //   a derived class ObjectStoreThreadWrapper is defined as follows:  //
  399.   //                                    //
  400.   //   class ObjectStoreThreadWrapper : omniORB::giopServerThreadWrapper//
  401.   //   {                                //
  402.   //     public:                            //
  403.   //       void run(void (*fn)(void*),void* arg) {            //
  404.   //         /* Setup the context to clean up the state attached by    //
  405.   //            ObjectStore to this thread */                //
  406.   //         OS_PSE_ESTABLISH_FAULT_HANDLER                //
  407.   //         fn(arg);                            //
  408.   //         OS_PSE_END_FAILUT_HANDLER                    //
  409.   //       }                                //
  410.   //  }                                    //
  411.   //                                    //
  412.   //  And in the main()                            //
  413.   //                                     //
  414.   //  omniORB::setgiopServerThreadWrapper(new ObjectStoreThreadWrapper);//
  415.   //                                    //
  416.   class giopServerThreadWrapper {                                       //
  417.   public:                                //
  418.     virtual void run(void (*fn)(void*), void* arg) { fn(arg); }        //
  419.     virtual ~giopServerThreadWrapper() {}                               //
  420.                                     //
  421.   // Install a new singleton. The old singleton will be deleted by the  //
  422.   // runtime. This function is not thread-safe and *SHOULD NOT* be used //
  423.   // when the BOA::impl_is_ready() has been called.                     //
  424.   // If the argument <p> is nil, the call will be siliently ignored.    //
  425.   // 
  426.     static void setGiopServerThreadWrapper(giopServerThreadWrapper* p);    //
  427.     static giopServerThreadWrapper* getGiopServerThreadWrapper();       //
  428.   };                                    //
  429.   ////////////////////////////////////////////////////////////////////////
  430.  
  431.   ////////////////////////////////////////////////////////////////////////
  432.   // class fatalException                                               //
  433.   //                                                                    //
  434.   // This exception is thrown if a bug inside the omniORB2 runtime is   //
  435.   // detected. The exact location in the source where the exception is  //
  436.   // thrown is indicated by file() and line().                          //
  437.   //                                                                    //
  438.   class fatalException {                                                //
  439.   public:                                                               //
  440.     fatalException(const char *file,int line,const char *errmsg) {      //
  441.       pd_file = file;                                                   //
  442.       pd_line = line;                                                   //
  443.       pd_errmsg = errmsg;                                               //
  444.     }                                                                   //
  445.     ~fatalException() {}                                                //
  446.     const char *file() const { return pd_file; }                        //
  447.     int line() const { return pd_line; }                                //
  448.     const char *errmsg() const { return pd_errmsg; }                    //
  449.   private:                                                              //
  450.     const char *pd_file;                                                //
  451.     int         pd_line;                                                //
  452.     const char *pd_errmsg;                                              //
  453.                                                                         //
  454.     fatalException();                                                   //
  455.   };                                                                    //
  456.   ////////////////////////////////////////////////////////////////////////
  457.  
  458.   friend class omni;
  459.   friend class CORBA;
  460. private:
  461.     static objectKey seed;
  462. };
  463.  
  464. #endif // __OMNIORB_H__
  465.